home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / pc / 3DTOSHI2.ZIP / myapp / doc / mpg3d.txt < prev    next >
Encoding:
Text File  |  1996-05-01  |  14.0 KB  |  468 lines
  1.  
  2. Multi-Platform 3D Graphics Library ver 2.0
  3.  
  4. 1 Introduction
  5.  
  6.   The purpose of Multi-Platform 3D Graphics library is to        
  7.   provide high-performance & flexible 3D graphics to 
  8.   high-level programmers. So that they do not have to build 
  9.   their own graphics routines for each target-platforms.
  10.  
  11. 2 Requirement
  12.  
  13.   Hardware :
  14.  
  15.     Minimum - 486 DX 33+ Mhz, 4 MB RAM, VGA Graphics Card. 
  16.     Recomended - Pentium 90+ Mhz, 8-16 MB RAM, VESA    
  17.                  compatible SVGA.
  18.  
  19.   Supported Operating System :
  20.  
  21.     DOS, 32-Bit DOS, Windows 3.1, Windows 95, Windows NT,     
  22.     OS/2 3.0, Unix with X Windows system.    
  23.  
  24.   Supported Compilers :
  25.  
  26.     Watcom C/C++ 10.0+, Visual C/C++ 2.0+, Borland C/C++ 
  27.     4.0+, GNU C/C++ Compiler.
  28.  
  29.   * You need MPGFX library to use MPG3D.
  30.  
  31. 3 Source Code
  32.  
  33.   The source code with gfx prefix is the C++ modules for 
  34.   this library. The source code with lgfx prefix is the 
  35.   Low-Level routine for this library.
  36.  
  37. G3D sources :  Extension C++ or CXX.
  38.  
  39.   g3d3ds   - Autodesk 3dstudio's 3DS file tool.
  40.   g3d3ds   - ASCII file tool.
  41.   g3dcam   - 3D Camera object class.
  42.   g3ddraw  - 3D drawing class.
  43.   g3dfile  - 3D file tool.
  44.   g3dgem   - GEM file tool.
  45.   g3dgeo   - ViewSpace GEO file tool.
  46.   g3dmath  - 3D vector tool.
  47.   g3dmatrl - Material class.
  48.   g3dlight - 3D light object class.
  49.   g3dobj   - 3D object base class.
  50.   g3dpobj  - 3D polygon object class.
  51.   g3dpoly  - 3D polygon class.
  52.   g3dshape - 3D shape class.
  53.   g3dsystm - 3D system class.
  54.   g3dworld - 3D world class.
  55.  
  56.  
  57. Low-Level sources  : Extension ASM or CPP or CXX.
  58.  
  59.   lg3dras? - 3D raster oprations.
  60.   lg3dmat? - 3D math routines.
  61.  
  62.   * Note - ? will be replaced by one of the following 
  63.            characters. 
  64.  
  65.      b  -  For Borland compiler.
  66.      g  -  For GNU compiler.
  67.      v  -  For Visual C/C++ compiler.
  68.      w  -  For Watcom C/C++ compiler.
  69.  
  70.   Use appropriate low-level source for your compiler.
  71.  
  72.  
  73. 4  Setup for MPG3D Library.
  74.  
  75.   Follow these steps to start programming with MPG3D.
  76.  
  77.     1 - Create directory called "MPG3D" or something you 
  78.         like.
  79.     2 - Under this directory, create "source" and "include".
  80.     3 - From source disks, copy all the files with  
  81.         cpp,cxx,asm extensions to the directory 
  82.         mpgfx/source.
  83.     4 - From source disks, copy all the files with h  
  84.         extensions to the directory mpg3d/include.
  85.     5 - Include all the g3d?.cpp ( or cxx ) modules and 
  86.         appropriate low-level source files to your project 
  87.         or makefile.
  88.     6 - You must define a macro before start compiling. See 
  89.         below.
  90.  
  91.       Macros for Compiler :
  92.  
  93.         __FORBORLAND__  - Compiling for Borland.
  94.         __FORGCC__      - Compiling for GCC.
  95.         __FORVISUAL__   - Compiling for Visual.
  96.         __FORWATCOM__   - Compiling for Watcom.
  97.  
  98.       Macros for Target Operating System :
  99.  
  100.         __FORDOS__      - 16 Bit DOS.
  101.         __FORDOS4GW__   - 32 Bit DOS 4GW Extender.
  102.         __FORWIN16__    - 16 Bit Windows.
  103.         __FORWIN32__    - 32 Bit Windows. ( Windows 95, NT, 
  104.                           Win32s )
  105.         __FOROS2__      - 32 Bit OS/2.
  106.         __FORUNIX__     - Unix with X Wndows.
  107.  
  108.       Macros for Tools or class library :
  109.     
  110.         __FORMFC__      - Make it compatible to MFC class 
  111.                           library.      
  112.         __FOROWL__      - Make it compatible to OWL class 
  113.                           library.      
  114.         __FORMOTIF__    - Make it compatible to Motil 
  115.                           Toolkit.
  116.  
  117.      * Exmaple -  If you want to compile for Windows 95 
  118.                   using Watcom C/C++ with MFC library, 
  119.                   define :
  120.  
  121.              __FORWATCOM__ __FORWIN32__ __FORMFC__
  122.  
  123.    7 - Make mpg3d/include directory visible to your project.
  124.    8 - Include stdgfx.h and mpg3d.h file in your source 
  125.        code.
  126.       
  127.  
  128. 5 Programming with MPG3D
  129.  
  130. 5.1 Important Classes.
  131.  
  132.   G3DSYSTEM - This is the main class. Almost all operations 
  133.               must go through this class's interface.  
  134.  
  135.   G3DWORLD  - This is the world class, containing various 
  136.               objects.
  137.  
  138.   G3DOBJECT - Base 3D Object class.
  139.  
  140.   G3DPOLYHEDRON - 3D polyhedron class inherited from 
  141.                   G3DOBJECT.
  142.  
  143.   G3DLIGHT  - 3D light object class inherited from 
  144.               G3DOBJECT.
  145.  
  146.   G3DCAMERA - 3D camera object class inherited from 
  147.               G3DOBJECT.
  148.  
  149.   G3DMATERIAL - Material is a class defines a 3D surface.
  150.   
  151.   G3DMATERIALLIB - Material library. Collection and 
  152.                    interface to many materials.
  153.  
  154. 5.2  Start programming
  155.  
  156.   You must follow these steps to start programming with MPG3D.
  157.  
  158.   1. Create an instance of G3DSYSTEM.
  159.   2. Create a world. ( Load objects, add lights, etc ... )
  160.   3. Create material library.
  161.   4. Create a camera.
  162.   5. Set some attribues of 3D system. ( Destination screen, 
  163.                                         Viewport, 
  164.                                         Viewdistance, etc..)
  165.   6. Show view through a camera.
  166.  
  167. Example 1
  168.  
  169.   void main ()
  170.     {
  171.       G3DSYSTEM *G3D = new G3DSYSTEM ();
  172.       G3DWORLD *World = new G3DWORLD ();
  173.       
  174.       LINKEDLIST<G3DOBJECT*> *ObjectList;
  175.       ObjectList = new LINKEDLIST<G3DOBJECT*> ();
  176.  
  177.       if (G3D->Load3DFile ( "test.3ds", ObjectList,        
  178.                             COUNTER_CLOCK_WISE,
  179.                             1.0 )==FAILURE)
  180.         {
  181.           printf ("Can not load this objects.");
  182.           exit(0);
  183.         } 
  184.  
  185.       G3DLIGHT *Light = new G3DLIGHT ();
  186.       COLORTABLE *ShadeTable = new COLORTABLE ();
  187.       ShadeTable->Load ( "shade.tbl" );
  188.       Light->SetPosition ( 0, 0, 0 );
  189.       Light->SetShadeTable ( ShadeTable );
  190.       Light->SetMinIntensity ( 0 );
  191.       Light->SetMaxIntensity ( ShadeTable->GetNumLevels() );
  192.  
  193.       World->AddObject ( Light );
  194.  
  195.       G3DMATERIALLIB *MaterialLib = new MATERIALLIB ();
  196.       MaterialLib->CreateTextures ( 1 );
  197.       MaterialLib->CreateMaterials ( 1 );
  198.       if (MaterialLib->LoadTexture(0,"test.pcx",           
  199.                                    TEXTURE_STATIC,
  200.                                   ShadeTable->GetPalette())
  201.           ==FAILURE)
  202.         exit(0);
  203.  
  204.       G3DMATERIAL *Material = MaterialLib->GetMaterial(0);
  205.       Material->Attributes = 0;
  206.       Material->Ambient = 15;  // Choose color 15
  207.       Material->SetTexture ( MaterialLib->GetTexture(0) );
  208.  
  209.       LISTOBJECT* ObjectNode;
  210.       ObjectNode = ObjectList->GetHead ();
  211.       while (ObjectNode!=NULL)
  212.         {
  213.           G3DOBJECT *Object = ObjectNode->Data;
  214.           Object->SetLightSource ( Light );
  215.           Object->SetPosition ( 0, 0, 500 );
  216.           
  217.           if (Object->GetObjectType()==
  218.                OBJECT_TYPE_POLYHEDRON)
  219.             {
  220.               G3DPOLYHEDRON *PolyObject = 
  221.                 (G3DPOLYHEDRON*)Object;
  222.               PolyObject->SetMaterial ( Material );
  223.             } // End if
  224.           World->AddObject ( Object ); 
  225.           ObjectNode = ObjectNode->NextObject;
  226.         }
  227.  
  228.       G3D->SetWorld ( World, FALSE );
  229.     
  230.       G3DCAMERA *Camera = new G3DCAMERA ();
  231.       Camera->SetPosition ( 0, 0, 0 );
  232.       Camera->SetAngle ( 0, 0, 0 );
  233.  
  234.       IMAGE *Vscreen = new IMAGE ();
  235.      
  236.       DISPLATDATA Data;
  237.       Data.Mode = M320x200x256;
  238.       Grafix.SetDisplay ( &Data );
  239.  
  240.       VScreen->Create ( IMAGE_8BIT, Grafix.GetWidth(HVGA),
  241.                         Grafix.GetHeight(HVGA) );
  242.       VScreen->Clear ( 0 );
  243.  
  244.       G3D->SetViewPort ( 0, 0, VScreen->GetWidth()-1, 
  245.                          VScreen->GetHeight()-1 );
  246.  
  247.       G3D->SetViewDistance ( 200.0 );
  248.       G3D->SetScreenCenter ( VScreen->GetWidth()/2, 
  249.                              VScreen->GetHeight()/2 );
  250.       G3D->ShowView ( Camera ); 
  251.       getch ();
  252.  
  253.       Grafix.ResetDisplay ();
  254.     } // End of main
  255.  
  256.  
  257. 5.3 G3DSYSTEM
  258.  
  259.   These are the interfaces to G3DSYSTEM.
  260.  
  261. G3DSYSTEM ();
  262.   - Constructor of 3D System.
  263.  
  264. ~G3DSYSTEM ();
  265.   - Destructor of 3D System.
  266.       
  267. VOID SetDestination ( IMAGE *Dest );
  268.   - Set the Destination of 3D System.
  269.     All 3D rasterization will be done to this destination.
  270.  
  271.     Dest - IMAGE type.
  272.  
  273. VOID SetViewDistance ( float ViewDistance );
  274.   - Set the distance between camera and view plane.
  275.  
  276.     ViewDistance - Distance in 4 bytes float.
  277.  
  278. VOID SetScreenCenter ( LONG CenterX, LONG CenterY );
  279.   - Set the center of the screen.
  280.  
  281.     CenterX - Center X coord.
  282.     CenterY - Center Y coord.
  283.  
  284. VOID SetMaterialLib ( G3DMATERIALLIB *NewLib );
  285.   - Set the Material Library.
  286.  
  287.     NewLib - NewMaterial Library.
  288.  
  289. VOID SetWorld ( G3DWORLD *NewWorld, BOOLEAN DeleteOld );
  290.   - Set the world.
  291.  
  292.     NewWorld - World to be set.
  293.     DeleteOld - Boolean.  If this is TRUE, then
  294.                 the previous world will be deleted.
  295.  
  296. VOID SetShadeFlags ( LONG Flags );
  297.   - Set the Shading limit.
  298.  
  299.     Flags - Valid values are
  300.  
  301.       SHADE_NONE    -  No shading.
  302.       SHADE_FLAT    -  Flat shading.
  303.       SHADE_GOURAUD - Gouraud shading. 
  304.  
  305. VOID SetFaceFlags ( LONG Flags );
  306.   - Set the Surface limit.
  307.  
  308.     Flags - Valid values are
  309.  
  310.       FACE_WIREFRAME - Faces will be wireframes.
  311.       FACE_SOLID     - Solid color face.
  312.       FACE_TEXTURE   - Texture mapped face.
  313.  
  314. VOID SetDepthCueing ( BOOLEAN OnOff, float Scale );
  315.   - Set depth cueing attributes.
  316.  
  317.     OnOff  - If TRUE, then depth cueing will be done.
  318.     Scale  - Scaling factor. If this value is small,
  319.              depth cueing gets faster. (darker).
  320.  
  321. VOID SetBlendTable ( COLORTABLE *Table );
  322.  
  323.   - Set the blending table. For transparent.
  324.  
  325.     Table - Table of blend type.
  326.       
  327. VOID SetHazing ( BOOLEAN OnOff, float Scale, 
  328.                  COLORTABLE *Table );
  329.   - Set the hazing (Foggy) effect.
  330.  
  331.     OnOff  -  Set TRUE for hazing on.
  332.     Scale  - Scaling factor.  If this values is small,
  333.              hazing gets faster. 
  334.     Table  - Haze table.
  335.  
  336. G3DMATERIALLIB* GetMaterialLib () { return MaterialLib; };
  337.   - Returns the material library.
  338.  
  339. G3DMATERIAL *FindMaterialByName ( STRING Name );
  340.   - Find the material by searching the name.
  341.     If no material is found, returns NULL.
  342.  
  343.     Name - String to be used for search.
  344.  
  345. G3DMATERIAL *FindMaterialByID ( LONG SearchID );
  346.   - Find the material by searching the ID.
  347.     If no material is found, returns NULL.    
  348.  
  349.     ID - Number to be used for ID.
  350.  
  351. G3DMATERIAL *FindMaterialByIndex ( LONG Index );
  352.   - Find the material by Index of array.
  353.     If no material is found, returns NULL.
  354.  
  355.     Index - Index to the array of material.
  356.             Starting from 0 to Num-1.
  357.       
  358. G3DWORLD* GetWorld () { return World; };
  359.   - Retuns the world.
  360.       
  361. G3DOBJECT* FindObjectByName ( STRING SearchName );
  362.   - Find object by searching the name.
  363.     If no object is found, returns NULL.
  364.  
  365.     SearchName - String to be used for search.
  366.  
  367. G3DOBJECT* FindObjectByID ( LONG SearchID );
  368.   - Find object by searching the ID.
  369.     If no object is found, returns NULL.
  370.  
  371.     SearchID - String to be used for search.
  372.       
  373. BOOLEAN Load3DFile ( STRING FileName, 
  374.                      LINKEDLIST<G3DOBJECT*> *ObjectList,
  375.                      BOOLEAN ClockWise, double Scale );
  376.   - Loads the objects in data file.
  377.  
  378.     FileName - File to be opened. Currently, following files 
  379.                are supported.
  380.      
  381.       3DS  -  Audesk 3D Studio's 3DS file.
  382.       ASC  -  ASCII file.
  383.       GEM  -  Geometry file.
  384.       GEO  -  ViewSpace's GEO file.
  385.  
  386.     ObjectList - Linked list of G3DOBJECT type.
  387.     Clockwise  - Set TRUE, if polygons must be loaded as      
  388.                  clockwised.
  389.     Scale      - Set the scal factor of object.
  390.  
  391. BOOLEAN Save3DFile ( STRING FileName, 
  392.                      LINKEDLIST<G3DOBJECT*> *ObjectList,
  393.                      BOOLEAN ClockWise, double Scale, 
  394.                      INT Type );
  395.   - Saves the objects to data file.
  396.  
  397.     FileName - File to be created. Currently, following
  398.                files are supported.
  399.      
  400.       GEO  -  ViewSpace's GEO file.
  401.  
  402.     ObjectList - Linked list of G3DOBJECT type.
  403.     Clockwise  - Set TRUE, if polygons be must saved as      
  404.                  clockwised.
  405.     Scale      - Set the scal factor of object.
  406.                         
  407. BOOLEAN Init ();
  408.   - Initializes the 3D system.  Must be called before 
  409.     Rendering.
  410.  
  411. VOID ShowView ( G3DCAMERA *Camera );
  412.   - Displays a view from camera to the destination.
  413.  
  414.     Camera - G3DCAMERA type.
  415.  
  416. VOID SetViewPort ( LONG x1, LONG y1, LONG x2, LONG y2 );
  417.   - Sets the viewport for rasterization.
  418.  
  419.     x1  -  Left extend for viewport.
  420.     y1  -  Top extend for viewport.
  421.     x2  -  Right extend for viewport.
  422.     y2  -  Bottom extend for viewport.
  423.  
  424. VOID SetNearClipZ ( float Z );
  425.   - Sets the minimum distance from camera for an object to
  426.     be visible.
  427.  
  428.     Z - Distance in float.
  429.  
  430. FLPVECTOR3D ComputeNextPos ( FLPVECTOR3D StartP, 
  431.                              FLPVECTOR3D Angle, 
  432.                              FLPVECTOR3D Vector );
  433.   - Computes the next position from starting position and
  434.     angle and speed.
  435.  
  436.     StartP  - Start coord.
  437.     Angle   - Angle to travel.
  438.     Vector  - Speed in each x,y,z coord.
  439.  
  440. LONG CheckCollision ( FLPVECTOR3D StartPt, 
  441.                       FLPVECTOR3D EndPt,
  442.                       COLLIDEDATA *CollideList, 
  443.                       LONG MaxNum,
  444.                       float CollideDist, float Gap );
  445.   - Check if collision occured while traveling from start
  446.     point to end point.  Returns the number of shapes that
  447.     collided.
  448.  
  449.     StartPt  - Start coord.
  450.     EndPt    - End coord.
  451.     CollideList - Arrays of collide data.
  452.  
  453.       struct COLLIDEDATA
  454.         {
  455.           G3DSHAPE *Shape;
  456.           float CollideT;  
  457.         }; // End of COLLIDEDATA
  458.  
  459.     MaxNum   - Maximum number of shapes to fill CollideList.
  460.     CollideDist - Minumum distance ratio for collision to
  461.                   occur. For example, 1.0 is exactly when
  462.                   collision occrus. 1.2 is when coliision
  463.                   occurs if vector travelled 0.2 times more 
  464.                   distance.
  465.     Gap - Distance for polygon extend.
  466.  
  467.  
  468.